Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support

GS/OS
#4:    A GS/OS State of Mind

Written by:    Matt Deatherage                                   January 1989

This Technical Note discusses GS/OS concepts and practices.
_____________________________________________________________________________


Introduction

Although GS/OS bears many similarities to ProDOS, GS/OS is a much wider-
reaching operating system, working not only with multiple file systems but 
also with character devices.  Some things which always worked under ProDOS 
cause problems under GS/OS, and application programmers need to be aware of 
the differences, particularly creators of text-based programs.


GS/OS Hints

Be aware of character devices.  A legal GS/OS pathname could be to a 
character device.  When prompted, a user could enter a pathname, which could 
have potentially disastrous results.  Error $58, Not a Block Device, can 
protect you against this on many calls, including Create, but you must still 
take precaution.  DInfo tells you if a device is a character device or block 
device; bit seven of the characteristics word is set if the device is a block 
device.

Don't preprocess pathnames.  A user input routine which prevents users 
from entering pathnames that don't follow ProDOS syntax may help prevent 
Illegal Pathname Syntax errors, but it also keeps users from creating files on 
non-ProDOS disks with anything but ProDOS pathname syntax, and it could keep 
them from accessing files on non-ProDOS disks which they created with another 
GS/OS application.  Since the only FST which allows you to write to a device 
under System Disk 4.0 is ProDOS, you don't see this problem right now, but 
under future versions of the System Disk with additional FSTs, this will not 
be the case.  To allow compatibility with future FSTs, we suggest you pass 
user-entered pathnames directly to GS/OS, with no application preprocessing.

Remember that under GS/OS both colons and slashes are valid separators, and 
colons can only be separators.  In addition, all eight bits of each byte of a 
pathname are significant.  Refer to GS/OS Reference, Volume 1 for more 
information on GS/OS pathname syntax.  Using all eight bits of each byte may 
be particularly difficult for text-based applications, which have no way to 
force the standard Apple II character set to display characters such as sigma
or the copyright symbol, although they can fiddle to get characters like the
sterling pound sign and an apple. Some programs may wish to adopt special
typographical conventions for these special characters while others may choose 
not to create files with such characters in their names.  These programs
could present the user with a list of existing file names (with some
substitution for the characters which are unavailable), while providing a
method of choosing one, to retrieve such files.  Any way around this problem
for a text-based program will be less than optimal.

Avoid the Text Tools and all slot dependencies.  Preliminary GS/OS 
documentation points to a System Service call named SlotArbiter.  Eventually 
this mechanism, presented only as a skeleton on System Disk 4.0, will allow 
the operating system to use all internal ports and external slots 
interchangeably, instead of requiring rebooting the machine to safely change 
between ports and slots.  Applications which have hard-coded slot dependencies 
(as the Text Tools unfortunately require) make this transition very difficult, 
both for GS/OS and for the applications and users.  We recommend that 
applications use the GS/OS loaded and generated character device drivers for 
text output.  A DInfo call will tell you what slot or port a driver controls, 
and whether or not it is a character device.

Avoid other file system dependencies.  Many of the things ProDOS 
programmers are used to as facts of life just are not true any longer.  For 
example, file names don't have to be 15 characters or less under GS/OS.  When 
making class one calls, GS/OS will tell you if you don't have enough room for 
the pathname by returning a Buffer Too Small error ($4F).  Avoiding file 
system dependencies means handling this error intelligently:  if you receive 
it, allocate more space for the buffer and try the call again.  GS/OS will 
tell you how much space is needed.  If you absolutely must hard code 
pathnames, such as volume names, be sure to use the colon as the separator, 
because if you do not, file names with slashes will cause problems.  
Similarly, don't assume and of the following:

o    There can only be 51 files in the volume directory
o    All devices are named ".Dn," where n is the device number
o    All blocks are 512 bytes long
o    All devices are block devices
o    Any other ProDOS-specific characteristics

Don't hog all of the memory.  While this is never a good idea on the 
IIGS, it's even worse under GS/OS.  To process things like pathnames, GS/OS 
allocates memory through the Memory Manager.  If you've allocated all of 
available memory (i.e., for a disk copy procedure), GS/OS will be forced to 
return an Out of Memory error ($54).  If the condition is so severe that GS/OS 
can no longer function, it will be a fatal GS/OS error with an ID = 2, and you 
will be asked to restart the system.

(A common cause of fatal GS/OS error 2 during development is using a length 
byte instead of a length word on a class one string.  Doing so almost always 
causes the first word to be greater than 8K, which is the maximum length of 
pathnames under GS/OS.  GS/OS then dies for your enjoyment, as it is unable to 
allocate the memory for the pathname because it's too big, even if more than 
8K is available.)

Hard code as little as possible.  Even seemingly static things like 
device names should not be hard coded, since a new loaded driver could change 
the name of the same device at any time.  Also, it may be possible in the 
future for users to rename devices.

Only ask for the access you need.  If you're just going to read a file, 
Open the file with read permission only.  In file systems where access 
privileges mean more than they traditionally have in ProDOS (where things are 
usually "Locked" or "Unlocked"), this could save some trouble.


Further Reference
_____________________________________________________________________________
o    GS/OS Reference, Volume 1
